C Routines for TI-84 Plus C Silver Edition
==============================

This repository contains a demostration of Z80 C programming on TI-84 PCSE.

Currently, it contains a file of simple C wrappers for system call routines,
and a simple demostration, showing the following operations.

* Toggling the CPU speed between 15 MHz and 6 MHz.
* "Hello, world!"
* Using AppVar
* Swapping memory-mapped pages
* Simple drawing by `rectfill()`

The main objective is demostrating the basic usability of C programming,
the code is written for clarity and abstraction from the perspective of
C application programmers, not for performance. This is especially true
for the assembly system call wrappers in `syscalls.c`.

Furthermore, in my point of view, as Z80 is a rather limited platform for C
programming, writing efficient code requires speaking a dialect of C - e.g. 
using only pointer arithmetics instead of counters, counting from upper
to lower, or registers instead of parameters on the stack - this already
defeats the purpose of simplicity and clarity by using C in the first place,

If efficiency matters, please use assembly, or a bunch of assembly with some C
glue code.

### Build ###

Before you run `make`, you need to install...

* `sed`, `wget` and `gcc` (`clang` is also okay).
    * These should be standard tools on a Unix-like programming environment.

* Latest [SDCC from snapshot](http://sdcc.sourceforge.net/snap.php).

* Kerm Martian's [BinPac8x](https://www.ticalc.org/archives/files/fileinfo/429/42915.html).
    * Rename `binpac8x.py` as `binpac8x`, and `chmod +x binpac8x`.

* Koen's [to8xv](https://bitbucket.org/keoni29/ti83f).

And don't forget to add them to your `$PATH`.

Finally, the demostration uses a non-free, proprietary artwork, which
is copyrighted by [ZUN](https://en.touhouwiki.net/wiki/ZUN) and its fan
artists, its corresponding files are `reimu.ppm`, and all generated files
`testvar.dat`, `testvar.dat.rgb565` and `testvar.dat.rgb565.rle`. It is
downloaded automatically during `make` from my web server.

According to the general ethics of the fanart community, using it solely
on your computer for this experiment should be acceptable, but don't
use it for any other purposes. The use of this artwork is intended for other
people to reproduce my previously published example.

### Credits ###

* SDCC maintainers, including [Erik Petrich](https://sourceforge.net/u/epetrich/), [Ben Shi](https://sourceforge.net/u/benshi/profile/), [Philipp Klaus Krause](https://sourceforge.net/u/spth/), and [Maarten Brock](https://sourceforge.net/u/maartenbrock/profile/), for helping solving [bugs](https://sourceforge.net/p/sdcc/bugs/2399/), after [bugs](https://sourceforge.net/p/sdcc/bugs/2386/), after [bugs](https://sourceforge.net/p/sdcc/bugs/2830/), after [bugs](https://sourceforge.net/p/sdcc/bugs/2831/), that I encountered, and providing people the possibility of writing programs for 8-bit machines without using assembly.

* AHelper's "[Write TI-83+/84+ C Programs for GlassOS and TIOS](https://www.cemetech.net/forum/viewtopic.php?t=7087)".

* [Tari](https://www.cemetech.net/forum/viewtopic.php?t=11596&highlight=) and [KermMartian](https://www.cemetech.net/forum/viewtopic.php?t=11745&highlight=)'s initial helps.

* [Unknown Loner](https://www.cemetech.net/forum/viewtopic.php?t=10678&highlight=)'s [documentation and code](https://github.com/faithanalog/wiki/blob/master/ti84cse/HalfRes.md) for Half Resolution Mode on the CSE.

### License ###

This software is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 3, or (at your option) any
later version.

GPL or LGPL **does not require attribution beyond preserving and following
the license**, but if you find my code is useful or inspirational to your
own project, I'd be thankful if you attribute my name.

This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.

See COPYING for terms and conditions.

**This software uses a derived verision of Z80 crt0.s library written by
Michael Hope, which is licensed under GPLv2+, but due to the linking exception,
if you use it to write programs with SDCC, its GPL status doesn't affect your
own code.**

#### crt0.s ####

`crt0.s` library is free software by Michael Hope; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or (at your
option) any later version.

As a special exception, if you link this library with other files, some of
which are compiled with SDCC, to produce an executable, this library does not
by itself cause the resulting executable to be covered by the GNU General
Public License. This exception does not however invalidate any other reasons
why the executable file might be covered by the GNU General Public License.

This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.

See COPYING.GPL2 and COPYING.GPL3 for terms and conditions.
